資料格式化 ¶

為了以更易讀的格式向使用者顯示資料，您可以使用 formatter 應用程式組件 來格式化它們。預設情況下，格式器由 yii\i18n\Formatter 實作，它提供了一組方法來將資料格式化為日期/時間、數字、貨幣和其他常用的格式。您可以像下面這樣使用格式器，

$formatter = \Yii::$app->formatter;

// output: January 1, 2014
echo $formatter->asDate('2014-01-01', 'long');
 
// output: 12.50%
echo $formatter->asPercent(0.125, 2);
 
// output: <a href="mailto:cebe@example.com">cebe@example.com</a>
echo $formatter->asEmail('cebe@example.com'); 

// output: Yes
echo $formatter->asBoolean(true); 
// it also handles display of null values:

// output: (not set)
echo $formatter->asDate(null); 

如您所見，所有這些方法都命名為 asXyz()，其中 Xyz 代表一種支援的格式。或者，您可以使用通用方法 format() 來格式化資料，它允許您以程式設計方式控制所需的格式，並且通常被 yii\grid\GridView 和 yii\widgets\DetailView 等小部件使用。例如，

// output: January 1, 2014
echo Yii::$app->formatter->format('2014-01-01', 'date'); 

// you can also use an array to specify parameters for the format method:
// `2` is the value for the $decimals parameter of the asPercent()-method.
// output: 12.50%
echo Yii::$app->formatter->format(0.125, ['percent', 2]); 

注意：格式器組件旨在格式化要顯示給最終使用者的值。如果您想將使用者輸入轉換為機器可讀的格式，或者只是以機器可讀的格式格式化日期，則格式器不是正確的工具。要轉換日期和數字值的使用者輸入，您可以分別使用 yii\validators\DateValidator 和 yii\validators\NumberValidator。對於機器可讀的日期和時間格式之間的簡單轉換，PHP 的 date() 函數就足夠了。

設定格式器 ¶

您可以通過在 應用程式配置 中配置 formatter 組件來自訂格式化規則。例如，

return [
    'components' => [
        'formatter' => [
            'dateFormat' => 'dd.MM.yyyy',
            'decimalSeparator' => ',',
            'thousandSeparator' => ' ',
            'currencyCode' => 'EUR',
       ],
    ],
];

有關可以配置的屬性，請參閱 yii\i18n\Formatter。

格式化日期和時間值 ¶

格式器支援以下與日期和時間相關的輸出格式

• date：值被格式化為日期，例如 January 01, 2014。
• time：值被格式化為時間，例如 14:23。
• datetime：值被格式化為日期和時間，例如 January 01, 2014 14:23。
• timestamp：值被格式化為 unix timestamp，例如 1412609982。
• relativeTime：值被格式化為日期和現在之間的時間間隔，以人類可讀的形式，例如 1 hour ago。
• duration：值被格式化為人類可讀格式的持續時間。例如 1 day, 2 minutes。

用於 date、time 和 datetime 方法的預設日期和時間格式可以通過配置全局自訂
dateFormat、timeFormat 和 datetimeFormat。

您可以使用 ICU 語法 指定日期和時間格式。您也可以使用帶有 php: 前綴的 PHP date() 語法，以將其與 ICU 語法區分開來。例如，

// ICU format
echo Yii::$app->formatter->asDate('now', 'yyyy-MM-dd'); // 2014-10-06

// PHP date()-format
echo Yii::$app->formatter->asDate('now', 'php:Y-m-d'); // 2014-10-06

資訊：PHP 格式語法的一些字母不被 ICU 以及 PHP intl 擴展所支援，因此不能在 Yii 格式器中使用。其中大多數 (w、t、L、B、u、I、Z) 對於格式化日期並非真正有用，而是用於進行日期數學運算。但是，S 和 U 可能很有用。它們的行為可以通過以下方式實現

• 對於 S，它是月份日期的英文序數後綴（例如 st、nd、rd 或 th.），可以使用以下替換

  $f = Yii::$app->formatter;
  $d = $f->asOrdinal($f->asDate('2017-05-15', 'php:j'));
  echo "On the $d day of the month.";  // prints "On the 15th day of the month."
  

• 對於 U，Unix Epoch，您可以使用 timestamp 格式。

當使用需要支援多種語言的應用程式時，您經常需要為不同的地區設定指定不同的日期和時間格式。為了簡化此任務，您可以改用格式快捷方式（例如 long、short）。格式器會根據目前活動的 地區設定 將格式快捷方式轉換為適當的格式。支援以下格式快捷方式（範例假設 en_GB 是活動的地區設定）

• short：日期將輸出 06/10/2014，時間將輸出 15:58；
• medium：將輸出 6 Oct 2014 和 15:58:42；
• long：將輸出 6 October 2014 和 15:58:42 GMT；
• full：將輸出 Monday, 6 October 2014 和 15:58:42 GMT。

從 2.0.7 版本開始，也可以在不同的日曆系統中格式化日期。有關如何設定不同日曆的信息，請參閱格式器 $calendar 屬性的 API 文檔。

時區 ¶

格式化日期和時間值時，Yii 會將它們轉換為目標 時區。除非明確給定時區，或者您已配置 yii\i18n\Formatter::$defaultTimeZone，否則要格式化的值將被假定為 UTC。

在以下範例中，我們假設目標 時區 設定為 Europe/Berlin。

// formatting a UNIX timestamp as a time
echo Yii::$app->formatter->asTime(1412599260); // 14:41:00

// formatting a datetime string (in UTC) as a time 
echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00

// formatting a datetime string (in CEST) as a time
echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00

如果未在格式器組件上明確設定 時區，則會使用 在應用程式中配置的時區，這與 PHP 配置中設定的時區相同。

注意：由於時區受世界各國政府制定的規則約束，並且可能會頻繁更改，因此您系統上安裝的時區資料庫中可能沒有最新的資訊。有關更新時區資料庫的詳細資訊，您可以參考 ICU 手冊。另請閱讀 設定 PHP 國際化環境。

格式化數字 ¶

格式器支援以下與數字相關的輸出格式

• integer：值被格式化為整數，例如 42。
• decimal：該值被格式化為十進制數字，考慮到小數和千位分隔符，例如 2,542.123 或 2.542,123。
• percent：值被格式化為百分比數字，例如 42%。
• scientific：值被格式化為科學記號格式的數字，例如 4.2E4。
• currency：值被格式化為貨幣值，例如 £420.00。請注意，為了使此函數正常工作，地區設定需要包含國家/地區部分，例如 en_GB 或 en_US，因為僅語言在這種情況下會產生歧義。
• size：作為位元組數的值被格式化為人類可讀的大小，例如 410 kibibytes。
• shortSize：是 size 的簡短版本，例如 410 KiB。

數字格式化的格式可以使用 decimalSeparator 和 thousandSeparator 進行調整，它們都根據活動的 地區設定 採用預設值。

對於更進階的配置，可以使用 yii\i18n\Formatter::$numberFormatterOptions 和 yii\i18n\Formatter::$numberFormatterTextOptions 來配置內部用於實現格式器的 NumberFormatter 類別。例如，要調整小數位數的最大值和最小值，您可以像下面這樣配置 yii\i18n\Formatter::$numberFormatterOptions 屬性

'numberFormatterOptions' => [
    NumberFormatter::MIN_FRACTION_DIGITS => 0,
    NumberFormatter::MAX_FRACTION_DIGITS => 2,
]

其他格式 ¶

除了日期/時間和數字格式之外，Yii 還支援其他常用的格式，包括

• raw：值按原樣輸出，這是一個偽格式器，除了 null 值將使用 nullDisplay 格式化之外，沒有任何效果。
• text：值是經過 HTML 編碼的。這是 GridView DataColumn 使用的預設格式。
• ntext：值被格式化為 HTML 編碼的純文本，其中換行符轉換為換行符。
• paragraphs：值被格式化為 HTML 編碼的文本段落，並包裹在 <p> 標籤中。
• html：值使用 HtmlPurifier 進行淨化，以避免 XSS 攻擊。您可以傳遞其他選項，例如 ['html', ['Attr.AllowedFrameTargets' => ['_blank']]]。
• email：值被格式化為 mailto 連結。
• image：值被格式化為圖像標籤。
• url：值被格式化為超連結。
• boolean：值被格式化為布林值。預設情況下，true 呈現為 Yes，false 呈現為 No，並翻譯為當前應用程式語言。您可以通過配置 yii\i18n\Formatter::$booleanFormat 屬性來調整此設定。

空值 ¶

空值會被特殊格式化。格式器不會顯示空字串，而是將其轉換為預設字串，預設字串為 (not set)，並翻譯為當前應用程式語言。您可以配置 nullDisplay 屬性來自訂此字串。

本地化資料格式 ¶

如前所述，格式器可以使用當前活動的 地區設定 來確定如何格式化在目標國家/地區適用的值。例如，相同的日期值對於不同的地區設定可能會以不同的方式格式化

Yii::$app->formatter->locale = 'en-US';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: January 1, 2014

Yii::$app->formatter->locale = 'de-DE';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1. Januar 2014

Yii::$app->formatter->locale = 'ru-RU';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1 января 2014 г.

預設情況下，目前活動的 地區設定 由 yii\base\Application::$language 的值確定。您可以通過顯式設定 yii\i18n\Formatter::$locale 屬性來覆蓋它。

注意：Yii 格式器依賴 PHP intl 擴展 來支援本地化資料格式。由於與 PHP 編譯的不同版本的 ICU 庫可能會導致不同的格式化結果，因此建議您在所有環境中使用相同的 ICU 版本。有關更多詳細資訊，請參閱 設定 PHP 國際化環境。

如果未安裝 intl 擴展，則資料將不會被本地化。

請注意，對於 1901 年之前或 2038 年之後的日期值，即使安裝了 intl 擴展，它們也不會在 32 位元系統上本地化。這是因為在這種情況下，ICU 使用 32 位元 UNIX 時間戳記來表示日期值。